<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Timeouts</title>
<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Chapter 1. Boost.Beast">
<link rel="up" href="../using_websocket.html" title="WebSocket">
<link rel="prev" href="control_frames.html" title="Control Frames">
<link rel="next" href="teardown.html" title="Teardown">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="control_frames.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../using_websocket.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="teardown.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="beast.using_websocket.timeouts"></a><a class="link" href="timeouts.html" title="Timeouts">Timeouts</a>
</h3></div></div></div>
<p>
        While <a class="link" href="../ref/boost__beast__basic_stream.html" title="basic_stream"><code class="computeroutput"><span class="identifier">basic_stream</span></code></a> and <a class="link" href="../ref/boost__beast__basic_stream.html" title="basic_stream"><code class="computeroutput"><span class="identifier">tcp_stream</span></code></a> support timeouts on general
        logical operations, the websocket stream has a more sophisticated timeout
        mechanism built-in which may be enabled and configured. The timeout features
        of the TCP or basic stream should not be used when working with a websocket
        stream. The interface to these timeout features is show in this table.
      </p>
<div class="table">
<a name="beast.using_websocket.timeouts.websocket_timeout_interface"></a><p class="title"><b>Table 1.35. WebSocket Timeout Interface</b></p>
<div class="table-contents"><table class="table" summary="WebSocket Timeout Interface">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                <p>
                  Name
                </p>
              </th>
<th>
                <p>
                  Description
                </p>
              </th>
</tr></thead>
<tbody>
<tr>
<td>
                <p>
                  <a class="link" href="../ref/boost__beast__websocket__stream_base__timeout.html" title="websocket::stream_base::timeout"><code class="computeroutput"><span class="identifier">stream_base</span><span class="special">::</span><span class="identifier">timeout</span></code></a>
                </p>
              </td>
<td>
                <p>
                  This represents configured timeout settings for a websocket stream.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a class="link" href="../ref/boost__beast__websocket__stream_base__timeout/suggested.html" title="websocket::stream_base::timeout::suggested"><code class="computeroutput"><span class="identifier">stream_base</span><span class="special">::</span><span class="identifier">timeout</span><span class="special">::</span><span class="identifier">suggested</span></code></a>
                </p>
              </td>
<td>
                <p>
                  This function returns the suggested timeout settings for a given
                  role (client or server).
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a class="link" href="../ref/boost__beast__websocket__stream/set_option.html" title="websocket::stream::set_option"><code class="computeroutput"><span class="identifier">stream</span><span class="special">::</span><span class="identifier">set_option</span></code></a>
                </p>
              </td>
<td>
                <p>
                  This function sets timeout and other options on the stream.
                </p>
              </td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break"><p>
        There are three timeout settings which may be set independently on the stream:
      </p>
<div class="table">
<a name="beast.using_websocket.timeouts.websocket_timeout_interface_2"></a><p class="title"><b>Table 1.36. WebSocket Timeout Interface (2)</b></p>
<div class="table-contents"><table class="table" summary="WebSocket Timeout Interface (2)">
<colgroup>
<col>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                <p>
                  Name
                </p>
              </th>
<th>
                <p>
                  Type
                </p>
              </th>
<th>
                <p>
                  Description
                </p>
              </th>
</tr></thead>
<tbody>
<tr>
<td>
                <p>
                  <a class="link" href="../ref/boost__beast__websocket__stream_base__timeout/handshake_timeout.html" title="websocket::stream_base::timeout::handshake_timeout"><code class="computeroutput"><span class="identifier">timeout</span><span class="special">::</span><span class="identifier">handshake_timeout</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">duration</span></code>
                </p>
              </td>
<td>
                <p>
                  This is the amount of time after which a handshake will time out.
                  The handshake timeout applies to client handshakes, server handshakes,
                  as well as the websocket closing handshake performed when either
                  end of the connection wish to shut down. The value returned by
                  <a class="link" href="../ref/boost__beast__websocket__stream_base/none.html" title="websocket::stream_base::none"><code class="computeroutput"><span class="identifier">stream_base</span><span class="special">::</span><span class="identifier">none</span><span class="special">()</span></code></a>
                  may be assigned to disable this timeout.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a class="link" href="../ref/boost__beast__websocket__stream_base__timeout/idle_timeout.html" title="websocket::stream_base::timeout::idle_timeout"><code class="computeroutput"><span class="identifier">timeout</span><span class="special">::</span><span class="identifier">idle_timeout</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><span class="identifier">duration</span></code>
                </p>
              </td>
<td>
                <p>
                  If no data is received from the peer for a time equal to the idle
                  timeout, then the connection will time out. The value returned
                  by <a class="link" href="../ref/boost__beast__websocket__stream_base/none.html" title="websocket::stream_base::none"><code class="computeroutput"><span class="identifier">stream_base</span><span class="special">::</span><span class="identifier">none</span><span class="special">()</span></code></a>
                  may be assigned to disable this timeout.
                </p>
              </td>
</tr>
<tr>
<td>
                <p>
                  <a class="link" href="../ref/boost__beast__websocket__stream_base__timeout/keep_alive_pings.html" title="websocket::stream_base::timeout::keep_alive_pings"><code class="computeroutput"><span class="identifier">timeout</span><span class="special">::</span><span class="identifier">keep_alive_pings</span></code></a>
                </p>
              </td>
<td>
                <p>
                  <code class="computeroutput"><span class="keyword">bool</span></code>
                </p>
              </td>
<td>
                <p>
                  If the idle timeout is enabled, then the value of this setting
                  controls whether or not a ping frame will be sent to the peer if
                  no data is received for half of the idle timeout interval.
                </p>
              </td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break"><p>
        By default, timeouts on websocket streams are disabled. The easiest way to
        turn them on is to set the suggested timeout settings on the stream.
      </p>
<pre class="programlisting"><span class="comment">// Apply suggested timeout options for the server role to the stream</span>
<span class="identifier">ws</span><span class="special">.</span><span class="identifier">set_option</span><span class="special">(</span><span class="identifier">stream_base</span><span class="special">::</span><span class="identifier">timeout</span><span class="special">::</span><span class="identifier">suggested</span><span class="special">(</span><span class="identifier">role_type</span><span class="special">::</span><span class="identifier">server</span><span class="special">));</span>
</pre>
<p>
        For manual control over the settings, a timeout options object may be constructed.
        Here we enable only the handshake timeout.
      </p>
<pre class="programlisting"><span class="identifier">stream_base</span><span class="special">::</span><span class="identifier">timeout</span> <span class="identifier">opt</span><span class="special">{</span>
    <span class="identifier">std</span><span class="special">::</span><span class="identifier">chrono</span><span class="special">::</span><span class="identifier">seconds</span><span class="special">(</span><span class="number">30</span><span class="special">),</span>   <span class="comment">// handshake timeout</span>
    <span class="identifier">stream_base</span><span class="special">::</span><span class="identifier">none</span><span class="special">(),</span>        <span class="comment">// idle timeout</span>
    <span class="keyword">false</span>
<span class="special">};</span>

<span class="comment">// Set the timeout options on the stream.</span>
<span class="identifier">ws</span><span class="special">.</span><span class="identifier">set_option</span><span class="special">(</span><span class="identifier">opt</span><span class="special">);</span>
</pre>
<p>
        Timeout notifications are delivered to the caller by invoking the completion
        handler for an outstanding asynchronous read operation with the error code
        <a class="link" href="../ref/boost__beast__error.html" title="error"><code class="computeroutput"><span class="identifier">error</span><span class="special">::</span><span class="identifier">timeout</span></code></a>.
        The implementation will close the socket or stream before delivering this
        error. It is not necessary to manually shut down the connection, as it will
        already be shut down. A read operation must be outstanding for the error
        to be delivered.
      </p>
<pre class="programlisting"><span class="identifier">ws</span><span class="special">.</span><span class="identifier">async_read</span><span class="special">(</span><span class="identifier">b</span><span class="special">,</span>
    <span class="special">[](</span><span class="identifier">error_code</span> <span class="identifier">ec</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span><span class="special">)</span>
    <span class="special">{</span>
        <span class="keyword">if</span><span class="special">(</span><span class="identifier">ec</span> <span class="special">==</span> <span class="identifier">beast</span><span class="special">::</span><span class="identifier">error</span><span class="special">::</span><span class="identifier">timeout</span><span class="special">)</span>
            <span class="identifier">std</span><span class="special">::</span><span class="identifier">cerr</span> <span class="special">&lt;&lt;</span> <span class="string">"timeout, connection closed!"</span><span class="special">;</span>
    <span class="special">});</span>
</pre>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../doc/src/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
          Websocket timeout features are available only when using asynchronous I/O.
        </p></td></tr>
</table></div>
<p>
        The timeouts on the websocket stream are incompatible with the timeouts used
        in the <code class="computeroutput"><span class="identifier">tcp_stream</span></code>. When constructing
        a websocket stream from a tcp stream that has timeouts enabled, the timeout
        should be disabled first before constructing the websocket stream, as shown.
      </p>
<pre class="programlisting"><span class="comment">// Disable any timeouts on the tcp_stream</span>
<span class="identifier">sock</span><span class="special">.</span><span class="identifier">expires_never</span><span class="special">();</span>

<span class="comment">// Construct the websocket stream, taking ownership of the existing tcp_stream</span>
<span class="identifier">stream</span><span class="special">&lt;</span><span class="identifier">tcp_stream</span><span class="special">&gt;</span> <span class="identifier">ws</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">sock</span><span class="special">));</span>
</pre>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2016-2019 Vinnie
      Falco<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="control_frames.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../using_websocket.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="teardown.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
